Comprehensive UTM tags documentation (backport of #712 to 7.3) - #996

Open in Promptless

Description

Backports the comprehensive UTM tags documentation from #712 onto the 7.3 branch, at the maintainer's request (@adiati98 asked in a PR comment to cherry-pick #712 to the 7.3 and 8.0 branches).

It replaces the single docs/channels/utm_tags.rst page with a dedicated eight-page UTM Tags section under docs/utm_tags/ — an overview plus per-feature guides for Landing Pages, Asset downloads, Forms, Emails, Dynamic Web Content, Campaign conditions, and Segment filters. The two inbound :doc: links (from Focus Items and Dynamic Web Content) are repointed to the new overview, the old page is removed, the UTM Tags toctree caption is added to the docs index, and CPC/DWC are added to the Vale vocabulary.

It started as a cherry-pick of #712 onto 7.3 and now also carries #712's 2026-10-01 review fixes, described below. The overview page's Google Analytics ID screenshot (add_google_analytics_id.png) already exists on 7.3 and resolves. The Forms page now includes the 'UTM tags recorded' timeline screenshot, captured from this branch's matching Mautic version (see below). Vale on the ported and changed lines is clean.

Linked issue

Backport of #712 (source PR). No issue to close from this PR.

Screenshots or screen recordings

Adds docs/channels/images/utm_tags/utm_tags_recorded_timeline.png, the 'UTM tags recorded' Contact timeline, captured from a local Mautic build matching this branch (see below).

Synced with #712 review of 2026-10-01 (verified against mautic/mautic 7.x)
At @adiati98's request, this PR now carries the same review fixes as #712 (commit 7065190a, plus follow-up 14fcf24c on promptless/utm-tags-712-ui-terms). Every Mautic term and UI label was checked against the 7.x branch's translation files and templates:

• Suggested wording applied: "Open the Form/DWC block/Email and edit its details", the Optional descriptions for utm_content and utm_term, and the title "Capturing UTM tags from Landing Pages".
• Alt text: the Google Analytics ID image alt text no longer starts with "Screenshot".
• Form-triggered: "Form" is a Mautic term, so the heading and body both use "Form-triggered".
• Record UTM Tags: this is the exact Form action label, so every mention is bold with no quotes.
• Contact field value: this is the condition's UI label, so every mention is bold.
• Condition paths: the UI shows unlabeled green and red connectors, so every mention reads "green 'yes' path" or "red 'no' path".
• Other UI labels corrected: the UTM group in the Contact Field dropdown, the Add a new submit action dropdown, the Download an asset Form action, the Choose one... filter menu, and lowercase /asset/ and utm_medium=email in example URLs.
• Segment filters: the step now names the five filters as the Choose one... menu lists them in the Contact group: UTM Campaign, UTM Content, UTM Medium, UTM Source, and UTM Term.
• Branch-specific (7.3): the Mautic 7.x labels match 7.0, so no version-specific wording was needed. The Forms page's screenshot TODO comment is now replaced with a real screenshot (see below).

Vale reports no new findings on docs/utm_tags/, and a local Sphinx build of this branch shows no warnings for the UTM pages.

Per-version 'UTM tags recorded' screenshot (2026-10-01)
At @adiati98's request, docs/channels/images/utm_tags/utm_tags_recorded_timeline.png on this branch is new. It replaces the leftover .. TODO: add screenshot comment on the Forms page. It was captured from a fresh local Mautic 7.x branch HEAD (9b35bfd3f7, the unreleased 7.3 line; its footer still reads v7.2.1) instance to match this PR's 7.3 base. To capture it, I created a Form with an Email field and the Record UTM Tags submit action, then submitted it as an anonymous visitor from /form/1?utm_source=newsletter&utm_medium=email&utm_campaign=spring_sale_2026&utm_content=welcome_email_1&utm_term=springsale. The image shows the Contact's History tab with the expanded UTM tags recorded entry: all five UTM values and FORMID: 1. It's framed the same way as the 7.0 screenshot in #965. The alt text matches the 7.0 image.

Vale reports no findings on docs/utm_tags/utm_tags_forms.rst.

Trigger Events

• GitHub comment request on PR #712 in mautic/user-documentation: EVERYTHING about UTM tags in Mautic
• GitHub PR review on mautic/user-documentation#712 asking to apply the 2026-10-01 review changes to the version PRs
• GitHub comment on mautic/user-documentation#965 asking for per-version 'UTM tags recorded' screenshots on each branch

Synced with #712 review (2026-10-02)
Applied @adiati98's two suggestions from the latest #712 review verbatim: the first step in docs/utm_tags/utm_tags_emails.rst now reads "Open the Email to start editing:" and the first step in docs/utm_tags/utm_tags_forms.rst now reads "Open the Form to start editing:". Vale reports no findings on the changed lines.

Synced with #712 DWC wording fix (2026-10-02)
At @adiati98's request on #712, the first step in docs/utm_tags/utm_tags_dynamic_web_content.rst now reads "Open the DWC block to start editing:", matching the Email and Form pages. This is the same change as commit f911efd on promptless/utm-tags-712-ui-terms. Vale reports no findings on the changed file.

Synced with #712 heading fix (2026-10-02)
Applied @adiati98's suggestion from #712 verbatim: the Recording UTM tags in Forms title in docs/utm_tags/utm_tags_forms.rst now has a 27-character # underline that matches the title length (it was one character too long). Vale reports no findings on the changed file.